BCI NET 2

home *** CD-ROM | disk | FTP | other *** search

/ BCI NET 2 / BCI NET 2.iso / archives / misc / zxam16b.lha / ZXAM Spectrum / ZXAM_Spectrum.DOCeng < prev next >

Wrap

Text File | 1995-01-28 | 56.3 KB | 1,350 lines

[0m[0 p [0;1;33;40mZXAM SPECTRUM EMULATOR v1.6b[0m © 1993-95 WareSoft All rights reserved by Antonio J. Pomar Rosselló [0;1mDISTRIBUTION[0m This program is SHAREWARE. This means that you can test the program during one month. After this period you must send $ US 15 (only CASH) to the author. In return you will receive the latest version available (probably the 128k version will be available by march 1995). By doing this contribution, you assure the further development of the emulator. Thanks in advance. This SHAREWARE version can be freely distributed provided that all the associated files are distributed with the program itself. Neither the program nor their associated files must be modified in any way. The complete distribution package can be compressed with LHA, LHarc or similar for distribution convenience. No charge must be made for use or distribution of this package. You can upload this package to any BBS, include it in a magazine's coverdisk or in a Public Domain library. The complete distribution package contains: ZXAM_SpectrumAGA The full AGA emulator (with icon). ZXAM_SpectrumAGA_FASTER Faster version for AGA (with icon). ZXAM_SpectrumOCS_ECS OCS/ECS version of the emulator (with icon). ZXAM_SpectrumOCS_ECS_FAST Faster version for OCS/ECS (with icon). ZXAM_Spectrum.DOCeng This is the english DOC (with icon). ZXAM_Spectrum.DOCesp Spanish translation of the DOC (with icon). README!! Notes for distribution (with icon). LEEME!! The same, but in spanish (with icon). INTERFACE.IFF Diagram of tape interface (with icon). DIGIT_INTERFACE.IFF Digitalization of my interface (with icon). powerpacker.library To load compressed spectrum programs. This software is provided 'AS IS' without warranty of any kind, either expressed or implied. By using this package you agree to accept the entire risk as to the quality and performance of the program, or even of the DOC. The same applies to the tape interface. It is prohibited to build and sell the tape interface for profit. The interface must be build for personal use only. All trademarks and Copyrights of products mentioned in this document are acknowledged by the author. In the DOC of the Spectrum Emulator 1.7 I have read that AMSTRAD has given special permission for emulator authors to use the Spectrum's ROM code. Anyway the Spectrum's ROM is copyright to AMSTRAD. The iff screen 'KeysHelp.iff' has been included with permission of the author (Mikael Ostergren). Thanks Mikael :-) The powerpacker.library is © Nico François. The Sinclair ZX Spectrum Emulator is © Peter McGavin. The Sinclair ZX Spectrum Emulator "Z80" is © Gerton Lunter. The emulator ZX Spectrum (SPEC386) is © Pedro Gimeno. [0;1mREQUIREMENTS[0m This program needs WorkBench 3.0 (v39) or higher to run, the AGA chipset and a 68020 CPU, or better. In short, an Amiga 1200 or 4000. It needs the powerpacker.library too, to load the compressed Spectrum programs, in LIBS: or in the same directory of the executable. For the filerequester the asl.library is used, but this library has a problem. Each time the filerequester is opened, the whole directory has to be read. This can be very annoying when loading files from floppy disks, or when you load it from a harddisk directory with a lot of files (400 files, in my case). The best solution could be to use the reqtools.library filerequester, as this requester has a buffer that avoid the re-reading of the directory, but due to serious technical problems I couldn't do it yet. Meanwhile the best option is to use the RTPatch program (by Nico François), that patches the asl/req/arp libraries to use the reqtools filerequester instead. This way the emulator, and other programs that use asl/req/arp, will use the reqtools filerequester, that is much better than the original ones. Curiously with RTPatch 1.3 (the one that I use) the buffer works well, but with ReqChange 3.0 (another patch that does the same) the buffer doesn't work. But, ¿what's AGA in the emulator? Well, I use some special AGA capabilities, not present in the OCS/ECS chipset, to convert the Spectrum's pixels and attributes to Amiga bitplanes. As you can see with the package there is an OCS/ECS version of the emulator. This version needs 68020+, WorkBench 2.04+ and any kind of chipset. This is a new version, and it hasn't been fully tested. Please, if you have any problem with this version, let me know (I can't test fully this version because I don't have a 2.04/ECS computer with 68020+ processor). This version uses a slower system for screen conversion to bitplanes than the AGA version (this is noticeable in games like Uridium). Anyway, in most cases there will be no difference between OCS/ECS and AGA systems. The only things missing in the OCS/ECS version is the possibility of monocrome/colour display and the FLASH of colors (that is emulated instead doing an INVERSE). Is VERY convenient that you have 32 bits FAST memory. With FAST memory the speed, and the sound, will be A LOT better. [0;1mINTRODUCTION[0m Well, maybe you have guessed that this program is a Sinclair ZX Spectrum 48k emulator, with all those lovely attributes and only one channel of 1 bit sound (sob...). [0;1mSPECTRUM PROGRAM FORMATS[0m Before you can understand the function of some of the gadgets of the program, you must learn something about the format of the Spectrum programs (often called 'snapshots'). On the disk, a Spectrum program is simply a file that contains a copy of the 48k of RAM of the Spectrum, along with all the registers of the Z80 CPU (the CPU of the Spectrum). The problem is that every Spectrum emulator (on any computer) uses a different format to save the memory and the registers. That means that a program saved with an emulator will not load into any other emulator. Instead of create my own format for the Spectrum program I have decided to support several formats of programs. You can decide what format you want to use for the programs, or use the emulator as a format conversor too. The four formats that I know, and that I have included in the emulator, are called (provisionally) PC, MIRAGE, Z80 and KGB. These formats are: PC: This is the format used by a nice emulator for the IBM PC, and compatibles, programmed in Spain by Pedro Gimeno. The executable is called SPEC386.EXE and the version I know is the 0.99D ß. This emulator needs a 386DX at 25MHz, with a 256k cache, to approach to the original Spectrum speed. These files are 49190 bytes long and have a .SP extension appended to the name. MIRAGE: This is the format used by the Spectrum Emulator 1.7 by Peter McGavin. These files are 49179 bytes long and have the .snapshot extension appended to the name. I recommend that you change the extension to .mirage, because there are many Sepctrum emulators that use the .snapshot extension and this can cause confusion. The format version supported by the ZXAM emulator is the post-1.6 version, that stores correctly the border colour. This is the same format used by the emulators (for PC) VGASPEC (*.SNA) and JPP (*.SP, by Arnt Gulbrandsen). Z80: This format (implemented since version 1.6) is the one used by the Spectrum emulator (for PC computers) called 'Z80' by G.A.Lunter. ZXAM can load the old Z80 format (version 1.45) and the new one (version 2.01) if the snapshot is a 48k one. If the snapshot is 128k, or needs the emulation of Interface I or any other hardware not supported by ZXAM, the snapshot will not be loaded. This format is implemented for loading only. KGB: This format (implemented since version 1.6b) is the one used by the KGB Spectrum emulator for Amiga computers. These files are always 49486 bytes long. I don't know who is the author as I have never seen any DOC file for this emultor. Probably is in disuse due to its incompatibility with version 2.0 and higher of AmigaDOS. This format is available for loading only. In all the cases the snapshots can be crunched with powerpacker. Notice that the emulator NEVER uses the filename extension for identify the format of the file. Instead, a series of checkings in the file structure are done for identifying it. You can use the extension you wish for the files, but if you don't include this extension in the pattern of filerequester (tooltype PATTERN in the emulator's icon) the files will not appear in it. There is another format, the .TAP one. This is not a snapshot format. Instead, it is a "tape" file that contents a series of headers an data blocks. There is an ARexx script with the emulator to "explode" these .TAP files into the corresponding .header and .bytes files (a lá Spectrum 1.7). This way you can load these files through the "load -> from disk" option. If you know any other format (for any computer, like Amiga, Cray, MAC, Atari or PC) please send to me the information that you have, along with a disk with several games saved in that format. In the next version of the emulator I will support that format. [0;1mRUNNING THE EMULATOR[0m You can run the emulator from WorkBench or SHELL. If you run it from the SHELL, it will "detach" from the SHELL window and will search the program's icon to read the ToolTypes. Any problem at startup will be reported by a requester. Available ToolTypes are: PATTERN= Here you can put the pattern (or 'filter') for the filerequester. Take a look at the user's manual of your Amiga to learn how to use these patterns. LOADPATH= The directory where the LOAD filerequester will be opened. This can be the directory where you have the Spectrum games in the HD. SAVEPATH= The directory where the SAVE filerequester will be opened. DEFFORMAT= The default format used to save the programs (PC, PC_PP, MIRAGE or MIRAGE_PP). Anyway, you can change this with the suitable gadgets. REXXPATH= The directory where you have the ARexx scripts for the emulator. The scripts names must end with the '.zxam' extension. ROMFILE= The external ROM to load over the internal one. The ROM can be compressed with powerpacker. You must be care about non-original ROMs, as they can produce incompatibility with certain games (not an emulator's fault ;-) PRERUN= Sets a command line to be executed by AmigaDOS right before starting the emulation. For exmaple, if "PRERUN=cpu nocache" the caches of CPU will be disabled. Before the PRERUN command line is executed the emulator will save the status of the caches for restore it when returning from emulation (with HELP key). This way you can have the caches disabled in the emulation but without having to disable de caches for the WorkBench too. POSTRUN= This command line will be executed right after returning from the emulation. The status of caches is restored BEFORE the POSTRUN is executed. LOADMODE= Sets the default mode for the ROM's LOAD routine (TAPE or DISK). SAVEMODE= Sets the default mode for the ROM's SAVE routine (TAPE, DISK or DISK_PP if you want that the data is crunched before SAVEing to the disk). [0;1mPROGRAM'S WINDOW[0m The window has several gadgets to load, save, etc.. All the gadgets with an underlined letter means that pressing that letter on the keyboard is like click on the gadget. The gadgets are: Load Program .- Opens the filerequester to choose the spectrum program that you want to load. The emulator will detect the format of the file and then will load it in the Spectrum's memory. IMPORTANT: the programs can be compressed with PowerPacker. That means to save lots of disk space. If you load a file that the program don't know, the Spectrum's memory will be trashed with that file, but this is harmless. This version of the emulator CAN load programs from tape, but you need to build the interface described in INTERFACE.IFF. Since version 1.5 the window of the emulator is an AppWindow. That means that you can drop icons inside the window and it will be loaded. If you drop a disk/drawer the filerequester will be opened in that disk/drawer. Reload.- Reloads the last loaded program, that appears in the 'loaded file' box. Save program.- Saves the complete memory and registers of the Spectrum in the format selected with the "SAVE FORMAT" gadgets. Actually they are saved uncompressed. POKE.- Guess what... "SAVE FORMAT" box .- Inside this box there are 4 gadgets to select the format you want to use to save the Spectrum programs. The formats are PC and MIRAGE, and the compressed forms PC_PP and MIRAGE_PP. RUN .- Starts the emulation. During the emulation the multi-task is stopped and the emulator takes TOTAL control over the machine. You can return to the WorkBench by pressing the HELP key. Reset & RUN.- Like RUN but forcing a RESET of the Spectrum. Run ARexx.- Opens a file requester to select the ARexx script to run. It will be opened on the path fixed by the REXXPATH ToolType. Only the files with the '.zxam' extension will be showed. Abort ARexx.- This gadget is under control of the ARexx script. Is the script that must enable it and read it when needed. The emulator simply says to the script if the gadget has been pressed. [0;1mMENUS & KEYBOARD[0m All the gadgets with an underlined letter means that pressing that letter on the keyboard is like click on the gadget. The help key brings the 'About...' requester. The ESC key quits the emulator. The TAB, an Shift+TAB, key activates and moves through the integer gadgets. In the menu you can find the 'About...' and 'Quit' items. Since the 1.6 version there is a new menu, called 'Options', that enables to control the LOAD/SAVE modes (to DISK or TAPE). [0;1mTHE SPECTRUM'S KEYBOARD[0m In the emulation the keyboard is like the one of the Spectrum, with some 'special' keys: <- Deletes a char (Shift+0) Ctrl Like pressing Caps+Symbol (E mode) Alt Like Symbol Shift Del Like Shift+1 (Edit) Help Returns to WorkBench Esc RESET!!! F1 Switches between colour/black&white modes. In CHIPMEM-only systems the DMA load of the memory slows down the CPU. If you switch to the black&white mode the DMA load is much smaller, thus the emulator will run about 10% faster and the sound will be A LOT better. F2 In black&white mode inverts the image. F6 Starts the transfer (the Spectrum's memory will be saved to tape ready to be loaded in a real Spectrum or in the emulator itself). Cursor keys Like the original cursor keys of Spectrum+ (Shift+5 6 7 8). , (key on the right of M) is the ',' (Symbol+N) . (2ª on the right of M) is the '.'(Symbol+M) ´ (3ª on the right of M) is the '"' (Symbol+P) Ñ (key on the right of L) is the ':' (Symbol+Z) ; (2ª key on the right of L) is the ';' (Symbol+O) (Symbols referent to the spanish Amiga 1200 keyboard) The keypad works complete. The Kempston joystick is emulated with the Amiga joystick. Maybe you will notice that you can't press simultaneously 2 keys in the same row of the keyboard. This is because you have an Amiga 1200, and its keyboard simply behaves in this very particular way. You can test it with any of those keyboard-playing Spectrum games (all the games!). [0;1mEMULATION[0m Details about the FULL version: - The original Spectrum ROM is inside the executable. - The R register is fully emulated. - In the F register the 2 unusued bits aren't emulated, and the emulation of H and N is partial. - The BCD is fully emulated. - All the undocumented instructions of the Z80 CPU are emulated. - Interrupt mode 0 is like interrupt mode 1 (RST $38). - No NMI (for what?). - The border is emulated on the copperlist. That means that you can't do fancy border effects, but the BORDER command works. - The transfer intructions are emulated at 32 bits level. - You can run the emulator in colour or black&white mode, and can switch the modes while running. This is mainly for computers with only CHIP memory. - FLASH fully emulated. - Sound emulated at OUT instruction level. - The kempston joystick is fully emulated at IN level. - Only partial screen sincronization. Some games will 'blink', for the moment. - The Spectrum screen is PAL 15KHz. Sorry, but no VGA monitors. - The screen is genlock compatible. - The emulator works even if VBR is not 0. >>>>>>>>> Addendum for version 1.3 ß <<<<<<<< - Loads from tape, by means of a patch in the Spectrum's ROM. - Saves to tape in REAL TIME, that means, is the Z80 emulation that is sending the sound to the tape, even with an Amiga 1200 without FAST and in colour mode (!!). - The border is nearly perfect. >>>>>>>>> Addendum for version 1.3b ß <<<<<<<< - The emulator includes a transfer. With this you can pass programs from disk to tape. >>>>>>>>> Addendum for version 1.6 <<<<<<<< - Now you can redirect the LOAD and SAVE routines of the Spectrum's ROM to DISK or TAPE. Details about the FAST version (v1.3 ß): - No BCD emulation. That means that the BASIC will print the numbers with strange symbols, but the calculatios are still correct. Some games don't print correctly the score. - The internal timings are less accurate. Some programs may behave in strange ways. - No R register emulation. - No SAVE to tape, and no stabilized sound. - No LOAD from tape. - The border is of slow type. (really, the FAST version is only for PLAYING!!) - The speed difference between the FAST and FULL versions is about 5% to 10% (depends on the program). Actually, I use the FULL version with my Amiga 1200 because I prefer an emulation more accurate. [0;1mAREXX PORT[0m Since version 1.4 ß the emulator has an ARexx port. This port is for writing scripts to support new file formats, assemble, disassemble, and any other thing you can think. The port has the name 'ZXAM_REXX', but you only need the name to test if the emulator is present. More on this below. With the emulator you have some example scripts (example but useful, I think). There is an example to load snapshots from ARexx, another to save the Spectrum's screen as IFF, for batch converting of formats, for listing the BASIC program inside the Spectrum memory, for extracting the ROM from the emulator, if you want to modify it for any reason, for disassemble the spectrum's memory and for discompose the .TAP files. Some of these scripts are simply examples of usage of the emulator's functions. A good sample of the possibilities of the ARexx port is the Monitor.zxam script (created by Leonardo Cocaña Galán). This script acts like a very simple disassembler, but can be greatly enhanced to be a full blown disassembler/monitor. Some of the scripts need some system commands (like requestchoice or multiview). If you doesn't have these commands you must modify the scripts to use the commands that you have. The ARexx port of the emulator is an unusual one. Intead of being a Command Host it is a Function Host. That means that the parameters are fomatted inside parentheses, separated by commas. Even if the function doesn't need parameters you must put and empty parentheses at the end. The advantages are that you can use the functions directly inside expressions, and you don't need to do ADDRESS ZXAM_REXX or OPTIONS RESULTS at the beginning of the script. All the functions begin with ZXAM to avoid interference with function's names of other Function Hosts and libraries. The names are case insensitive. The 56 functions implemented in version 1.6b (39.21) are: ZXAMGetReg: Gets the contents of a register, 8 or 16 bits. Look at 'Registers' section for more details. The optional parameter 'format' sets the format of the value returned ('h' for hexadecimal and 'd' for decimal). The default format is decimal. format: value = ZXAMGetReg( register , [format] ) ------------------------------------------------------------------------------- ZXAMSetReg: Puts an 8 or 16 bits value inside a Z80 register. Look at 'Registers' section for more details. format: ZXAMSetReg( register , value ) ------------------------------------------------------------------------------- ZXAMPeek: Reads a byte from the specified address. format: value = ZXAMPeek( address ) ------------------------------------------------------------------------------- ZXAMPoke: Writes a byte at the specified address. format: ZXAMPoke( address , byte ) ------------------------------------------------------------------------------- ZXAMDPeek: Reads a 16 bit value from the Spectrum's memory. The value is read with the z80 format, that is, less significant byte first. format: value = ZXAMDPeek( address ) ------------------------------------------------------------------------------- ZXAMDpoke: Writes a 16 bit value from the Spectrum's memory. The value is written with the z80 format, that is, less significant byte first. format: ZXAMDPoke( address , value ) ------------------------------------------------------------------------------- ZXAMPutMem: Puts a string in the memory. Usually the string is a block of bytes, or the entire spectrum's memory. format: ZXAMPutMem( address , string ) ------------------------------------------------------------------------------- ZXAMGetMem: Copies the contents of the specified block to the result string. format: string = ZXAMGetMem( address , size ) ------------------------------------------------------------------------------- ZXAMFindByte: Searchs the specified byte, starting from the address. If the top of the spectrum's memory is reached without finding the byte, a -1 will be returned. If the byte is found, the address of the byte is the result. format: address = ZXAMFindByte( address , byte_to_search ) ------------------------------------------------------------------------------- ZXAMRun: Starts the emulation. format: ZXAMRun() ------------------------------------------------------------------------------- ZXAMQuit: Quits the emulator. format: ZXAMQuit() ------------------------------------------------------------------------------- ZXAMppLoadFile: Loads a file through the powerpacker.library and puts the complete file in the result string. If the file wasn't compressed, it will be loaded anyway. format: string = ZXAMppLoadFile( path_&_name ) ------------------------------------------------------------------------------- ZXAMPPSaveFile: Saves a block of bytes to a file, compressing it with powerpacker.library. If you don't want that the file be compressed, use the ARexx own file commands. format: ZXAMppSaveFile( path_&_name , string ) ------------------------------------------------------------------------------- ZXAMLoadRequester: Opens the LOAD filerequester. The title is for the top bar of the requester. The path for open the requester is optional. If no path is specified, the last path used with the requester will be used. If 'path_&_name' is empty means that the 'cancel' has been pressed. format: path_&_name = ZXAMLoadRequester( title , [path] ) ------------------------------------------------------------------------------- ZXAMSaveRequester: Opens the SAVE filerequester. The title is for the top bar of the requester. The path for open the requester is optional. If no path is specified, the last path used with the requester will be used. If 'path_&_name' is empty means that the 'cancel' has been pressed. format: path_&_name = ZXAMSaveRequester( title , [path] ) ------------------------------------------------------------------------------- ZXAMNameFormat: Puts the strings 'name' and 'format' in the 'Loaded file' and 'Format' boxes of the emulator's window. format: ZXAMNameFormat( name , format ) ------------------------------------------------------------------------------- ZXAMActName: Returns the contents of the 'Loaded file' box. If there is no name an empty string will be returned. format: name = ZXAMActName() ------------------------------------------------------------------------------- ZXAMActLoadPath: Returns the last path used in the LOAD filerequester. format: path = ZXAMActLoadPath() ------------------------------------------------------------------------------- ZXAMActSavePath: Returns the last path used in the SAVE filerequester. format: path = ZXAMActSavePath() ------------------------------------------------------------------------------- ZXAMActFormat: Returns the contents of the 'Format' box. If there is no format an empty string will be returned. format: formato = ZXAMActFormat() ------------------------------------------------------------------------------- ZXAMActSaveFormat: Returns the format actually selected for SAVE. The result can be PC, MIRAGE, PC_PP and MIRAGE_PP. format: format = ZXAMActSaveFormat() ------------------------------------------------------------------------------- ZXAMProgVersion: Returns the internal version of the emulator (version 1.5 will return '39.16'). This is for scripts that uses functions available only since certain version (if you want to know the version at which appears certain function, look at the HISTORY at the end of this DOC. format: version = ZXAMProgVersion() ------------------------------------------------------------------------------- ZXAMSaveFormat: Selects a format for SAVE. Can be PC, MIRAGE, PC_PP or MIRAGE_PP. format: ZXAMSaveFormat( formatname ) ------------------------------------------------------------------------------- ZXAMParseLoaded: Tries to load in memory the block passed as string of bytes. If the format is known (PC, MIRAGE, Z80 or KGB, without compression) then the memory and registers will be loaded with the passed block. The function will return the name of the format of the block. If the format is unknown then the function will return an empty string, and nothing is modified. format: format = ZXAMParseLoaded( block ) ------------------------------------------------------------------------------- ZXAMParseToSave: Returns the contents of the memory and registers in the format selected for SAVE (without compression). format: block = ZXAMParseToSave() ------------------------------------------------------------------------------- ZXAMJoinPathName: Joins the path and the name. format: path_&_name = ZXAMJoinPathName( path , name ) ------------------------------------------------------------------------------- ZXAMGetScr: Returns the actual Spectrum screen in interleaved format, 4 bitplanes, ready to be saved inside a IFF ILBM file. format: block = ZXAMGetScr() ------------------------------------------------------------------------------- ZXAMClearNameFormat: Deletes the 'Loaded file' and 'Format' boxes. format: ZXAMClearNameFormat() ------------------------------------------------------------------------------- ZXAMLoadPath: Modifies the path of the LOAD requester. format: ZXAMLoadPath( path ) ------------------------------------------------------------------------------- ZXAMSavePath: Modifies the path of the SAVE requester. format: ZXAMSavePath( path ) ------------------------------------------------------------------------------- ZXAMFilePart: Returns only the filename from a full path. format: name = ZXAMFilePart( path_&_name ) ------------------------------------------------------------------------------- ZXAMPathPart: Returns only the path from a full path. format: path = ZXAMPathPart( path_&_name ) ------------------------------------------------------------------------------- ZXAMPreRun: Modifies the PRERUN command line. format: ZXAMPreRun( command_line ) ------------------------------------------------------------------------------- ZXAMActPreRun: Returns the actual PRERUN command line. format: command_line = ZXAMActPreRun() ------------------------------------------------------------------------------- ZXAMPostRun: Modifies the POSTRUN command line. format: ZXAMPostRun( command_line ) ------------------------------------------------------------------------------- ZXAMActPostRun: Returns the actual POSTRUN command line. format: command_line = ZXAMActPostRun() ------------------------------------------------------------------------------- ZXAMPattern: Modifies the pattern for the file requesters. format: ZXAMPattern( pattern ) ------------------------------------------------------------------------------- ZXAMActPattern: Returns the actual pattern for the file requesters. format: pattern = ZXAMActPattern() ------------------------------------------------------------------------------- ZXAMBASICToken: Returns the expanded token string equivalent to the character supplied. For example, ZXAMBASICToken('ff'x) will return 'COPY'. All characters from 0 to 255 are translated according to the Spectrum's character table. format: string = ZXAMBASICToken( character ) ------------------------------------------------------------------------------- ZXAMReadAbort: Returns 0 or 1, depending if the 'Abort ARexx' gadget has been pressed. format: pressed = ZXAMReadAbort() ------------------------------------------------------------------------------- ZXAMClearAbort: Clears the flag that is set when 'Abort ARexx' is pressed. format: ZXAMClearAbort() ------------------------------------------------------------------------------- ZXAMNoReload: Disables the 'Reload' gadget. This must be done when you leave permanently changed the contents of the 'Loaded File' box. format: ZXAMNoReload() ------------------------------------------------------------------------------- ZXAMEnableAbort: Enables the 'Abort ARexx' gadget. This must be done if you want to read it (when runnig an ARexx script the gadget is disabled by default). format: ZXAMEnableAbort() ------------------------------------------------------------------------------- ZXAMDisableAbort: Disables the 'Abort ARexx' gadget. If you don't want to read the gadget, you can disable it. format: ZXAMDisableAbort() ------------------------------------------------------------------------------- ZXAMDisassemble: Disassembles the Z80 instruction placed in the given address and returns a string formatted the following way: - 1 ASCII character that says the number of bytes length of the instruction. This is useful to increment the memory pointer this number and thus point to the next instruction. This char must be excluded when printing the disassemble. - the rest of the string is the typical Z80 disassemble in the usual 'address+object code+mnemonic' format. If the instruction disassmebled is a relative jump (JR, DJNZ, etc) a comment will be appended to the line with the destination address of the jump. The illegal instructios will be presented as '---'. The optional parameter "format" sets the format of the number printing of address and data. 'H' means hexadecimal and 'D' means decimal. The default is hexadecimal. format: ZXAMDisassemble( address , [format] ) ------------------------------------------------------------------------------- ZXAMLoadMode: Sets the mode for the LOAD patch (that means, sets the state of the LOAD MODE menu). The mode is a string ('TAPE' o 'DISK'). format: ZXAMLoadMode( mode ) ------------------------------------------------------------------------------- ZXAMSaveMode: Sets the mode for the SAVE patch (that means, sets the state of the SAVE MODE menu). The mode is a string ('TAPE', 'DISK' or 'DISK_PP). format: ZXAMSaveMode( mode ) ------------------------------------------------------------------------------- ZXAMActLoadMode: Returns the actual mode of the LOAD patch (that means, the status of the LOAD MODE menu). The result is a string ('TAPE' or 'DISK'). format: mode = ZXAMActLoadMode() ------------------------------------------------------------------------------- ZXAMActSaveMode: Returns the actual mode of the SAVE patch (that means, the status of the SAVE MODE menu). The result is a string ('TAPE', 'DISK' or 'DISK_PP'). format: mode = ZXAMActSaveMode() ------------------------------------------------------------------------------- ZXAMAbout: Shows the 'About...' requester. format: ZXAMAbout() ------------------------------------------------------------------------------- ZXAMFindBlock: Search for a series of bytes in the Spectrum's memory. The first argument is the starting address for searching, and the second is the bytes for search in a string. That means, for searching 'HELLO' we must do ZXAMFindBlock(0,'HELLO'), anf for searching the bytes 0F 45 7B we must do ZXAMFindBlock(0,'0F457B'x). If de hexadecimal string is in a variable, then you must use x2c(variable) in the second argument. This way ARexx will translate the hexadecimal sctrind in the corresponding bytes. The result is the address where the bytes has been found, or -1 if they hasn't been found. format: address = ZXAMFindBlock( address , block_for_search ) ------------------------------------------------------------------------------- ZXAMDoChecksum: Does a checksum like the one that does the ROM's SAVE routine, that means, does a XOR (exclusive OR) of all the bytes of a block of bytes. The parameters are the starting address of the block and the length (number of bytes) of this block. The result is the XOR of all those bytes. format: result = ZXAMDoChecksum( address , number_of_bytes ) ------------------------------------------------------------------------------- ZXAMBreakPoint: Puts a breakpoint at the given address of the Spectrum's memory. If while the execution of code the Z80 arrives to the breakpoint, the emulator returns to the WorkBench (like if the 'HELP' key has been pressed) and the breakpoint will disappear. Only ONE breakpoint can be in memory. The execution of ZXAMBreakpoint() deletes the previous breakpoint. If the given address is 0 then the previous breakpoint will be deleted, and no new breakpoint will be put. The breakpoint is an instruction. That means that if the program modifies the memory address where the breakpoint is put, it will disappear. The breakpoint only survives to one entering into the emulator. As soon as you press 'HELP' to exit to the workbench, the breakpoint will disappear (the exit for load/save to disk doesn't delete the breakpoint). format: ZXAMBreakPoint( address ) ------------------------------------------------------------------------------- ZXAMTrace: Executes the instruction addressed by the Program Counter (without disabling the system). At the return, the function returns the disassembling of the executed instruction (in the same format than ZXAMDisassemble()). The 'format' parameter sets if the disassembling is decimal ('d') or hexadecimal ('h'). It's optional, and the default mode is hexadecimal. Neither the CIAs nor the audio channels need to be allocated to run step-by=step code. format: diassem = ZXAMTrace( [format] ) ------------------------------------------------------------------------------- ZXAMDoInt: Does an interruption (like if the INT signal has arrived to the Z80 processor), that means, puts PC in the stack, and sets the PC to the value appropriate to the actual Interrupt Mode ($38 if IM1, and the vector pointed by I if IM2). If the interrupts are disabled the function does nothing. format: ZXAMDoInt() ------------------------------------------------------------------------------- ZXAMBlockOfRegs: Returns a block of 27 bytes that contains all the registers and internal status of the Z80 processor. The block's structure is: Pos Size Contents 0 1 A 1 1 F 2 2 BC 4 2 DE 6 2 HL 8 1 A' 9 1 F' 10 2 BC' 12 2 DE' 14 2 HL' 16 2 IX 18 2 IY 20 2 SP 22 2 PC 24 1 Interrupt Status (0=disabled / 1=enabled) 25 1 Interrupción Mode (0, 1 or 2) 26 1 Border Colour (0 to 7) The 2 bytes registers are in 68000 format, that means, the most significant byte comes FIRST. This function is for passing the whole register set to other programs, like a disassembler/monitor, instead of having to get the registers one by one. format: block = ZXAMBlockOfRegs() ------------------------------------------------------------------------------- REGISTERS: the registers for use with ZXAMGetReg and ZXAMSetReg are: -8 bit registers: write his name (A, d, etc...). Even the indivisible 16 bit registers can be accessed by halves. For example, SPH and SPL are the two halves of SP. -16 bit regiters: write his name, like HL or PC. AF isn't implemented. -inverted 16 bit registers: swapping the letters of the name of a 16 bit register you will read/write on it but swapping the upper and lower bytes. -special "registers": INT : status of interrupts (0=OFF, 1=ON) IM : interrupr mode (0, 1 or 2) BOR : actual border colour (0 to 7) in all the cases you can append a '2' to the register name for accessing to the alternative set of registers (hl' = hl2 and a' = a2). The registers are case insensitive. All the registers can be read and written. [0;1mTECHNICAL INFO[0m Program written in assembler from the first lines to the full 17750 actual lines (151023 lines when expanding MACROs!!!). In my Amiga 1200 with hard disk and 68030/28MHz the Devpac 3.02 assembles the emulator in 51 secs (3 min 50 secs with a bare A1200, and 4 min 53 secs for the last version assembled with my Amiga 500 Plus). Well, if programming is fun... BIG programming is BIG fun! This is my third program in assembler. I began to program it in my Amiga 500 Plus with 2 Meg of RAM and 3 floppy drives. As soon as I can I bought an Amiga 1200 and converted the emulator to AGA-only and 68020 code. I began the emulator to experiment with the 68020 code. At the beginning I was programming conditionally in 68000 and 68020 code, and testing the emulator in the Amiga 4000/030 of a friend. With the new Amiga 1200 I have experimented with the AGA chips, and discarded totally the 68000 code. [0;1mPRE-HISTORY (jurassic?, NO! Around summer 1993![0m) The first black&white/CLI-only version, with ManicMiner inside the executable, worked in 10 days (phew!). Since then there are 6 different colour emulation systems, and 4 major restructurations of the Z80 emulation. None of the pre-AGA versions has been released to the public. This is not a full time project. While developing the emulator I was studying a little automations course, developing the MPMaster program and practising my laziness. [0;1mHISTORY[0m Version Internal version 1.0 ß 39.00 (11-March-94) -First public release. (distributed as ZXAM Spectrum Emulator AGA 1.0 ß) 1.1 ß 39.01 (2-April-94) (renamed ZXAM_SureCrash) -Audio filter off when emulating. Restored at exit. -Disabled nearly all of the interruptions. The sound is now a lot better. -The system keyboard handler 'freezes' after a while. I have to use this handler because of the new keyboard hardware of the Amiga 1200 (snort!). 39.02 (19-April-94) -Added the ZOOM gadget to the window. -The #%$&! system keyboard handler is still 'freezing'. (never distributed) 1.2 ß 39.03 (26-January-94) -¡At last! Fixed the problem with the system keyboard handler. -Now, if you press the Caps Lock key the system will be informed correctly about its state. -Available the FULL (complete) and FAST (faster) versions. The FAST version is about 10% faster, but it is a less detailed emulation (no BCD, no R register, etc...). 39.04 (27-January-94) -The emulator 'detachs' from the SHELL window. -The icon ToolTypes will be read even if the emulator runs from the SHELL. 39.05 (29-January-94) -No more audio problems. If a player (like Delitracker) is playing when starting the emulation, it will be stopped until return to the WorkBench (at least, with the players that I have). 39.06 -The Timer-B of CIA-B is allocated. -Preparatory version with some synchronizations with CIA Timer for future implementations of LOAD/SAVE to tape. (distributed as ZXAM Spectrum Emulator AGA 1.2 ß) 1.3 ß 39.07 (7-July-94) -First attempt of patching the ROM LOAD routine. Now you can LOAD from tape even in colour mode, with an Amiga 1200 with no FAST memory, and even with the FLASH working during the LOAD (!!). The patch seems to be very good, and works perfectly over the Amiga 1200 and Amiga 4000/030, but needs testing in other configurations. -Synchronized the OUT instruction. With this we have REAL TIME SAVE (not patched!!), and a pure tone BEEP. Some games now sounds A LOT better, but other have slowed down a little. 39.08 (11-July-94) -REAL border! Now, if there is enough speed, you can see the fancy border effects that some programs do. -Readjusted the proportion of bright added to the colours when BRIGHT 1. Now looks much more like the original Spectrum. -Readjusted the LOAD patch. Still loads very well, but now reacts better to the BREAK, HELP ans ESC keys. -¡At last! I have managed to do that the lines counter of Devpac 3.02 "turns around" for the second time. Now the assembled lines (with the macros expanded) are 133637 (!!). 39.09 (16-July-94) -Fixed the problem of the LOAD patch and OUT instruction with the border. Now the border is nearly perfect. Some border changes are missed because of interferences between the CPU and the copperlist. To see the border lines while LOADing or SAVEing is more than enough. (distributed as ZXAM Spectrum Emulator AGA 1.3 ß) 1.3b ß 39.10 (23-July-94) -The emulator now includes a "transfer", that can pass Spectrum programs from disk to tape. Initially included for my personal use for the speed comparisions between my Amiga 1200 and my old Spectrum +2A. -When the program is saved to tape, it will be saved with the name used to load it from disk. -The transfer don't uses his own LOAD routine. It uses the ROM load routine. That means that even the emulator itself can load "tranferred" programs. -The transfer can be stopped with the HELP key. -The transfer saves even de border colour. -When you do "Save Program" the new name is passed to the "Loaded file" box. This way we can do "Reload" of the last saved program. -The SAVE requester stores a different path that the Load requester. This way is easier to do multiple format conversions. -If no program is loaded, the transfer saves the program with the name LOADER. 39.11 (31-July-94) -Some adjustements done on the emulator synchronization. The sound is still stabilized, but some programs (like Manic Miner) have speeded up a little. -Fixed a bug with the transfer. -Fixed the problem of Kempston joystick with Panama Joe and Commando. -The border changes are now even faster. (distributed as ZXAM Spectrum Emulator AGA 1.3b ß) 1.4 ß 39.12 (2-September-94) -Fist attempt to add an ARexx port to the emulator. It works very well. Impemented functions GetReg, SetReg, Peek, Poke and Putmem. 39.13 (10-September-94) -Now the menus are NewLook. -Added several ARexx functions. Implemented functions DPeek, DPoke, FindByte, and the reversed access to registers. -Added code to run ARexx scripts, but there isn't gadget for that thing yet. -Written some scripts. 39.14 (16-September-94) -Added internal version to About... -Added the ROMFILE ToolType, to load external ROMs. The ROM can be compressed with powerpacker. -The name of the last loaded/saved program now appears in the SAVE filerequester, but with the extension of the actually seleted SAVE format. -Added more ARexx functions: ProgVersion, ActSaveFormat, SaveFormat, ParseToSave, ParseLoaded, JoinPathName, ClearNameFormat, GetScr, FilePart, PathPart, LoadPath and SavePath. -Modified the scripts to use the "powerpacked" functions. -Added the 'Run ARexx' gadget. The gadget opens a filerequester to select the script you want to run. -Added ToolType REXXPATH to specify the path where open the 'Run ARexx' filerequester. Extension is always '.zxam. -When you run it from the CLI, it will do CD to de path where the executable is placed. Every path must be relative to the executable's directory, or must supply a full path. (never distributed) 1.5 39.15 (28-September-94) -Added the option to save the programs compressed with powerpacker.library. -Reused the 'Save format' buttons. Now there are 2 buttons for each format (raw and compressed). -Added my FidoNet address to the About ;-) -Added more ARexx functions: ProgVersion, ActSaveFormat, SaveFormat, ParseToSave, ParseLoaded, JoinPathName, ClearNameFormat, GetScr, FilePart, PathPart, LoadPath SavePath, PreRun, ActPreRun, PostRun, ActPostRun, Pattern, ActPattern and BASICToken. -If the ARexx port can't be created succesfully the 'Run ARexx' gadget is disabled. -Added the option to add a title to the LOAD and SAVE filerequesters when used from ARexx. -Now the emulator returns properly the memory when there is no WB 3.0+, 68020+ or AGA chipset. -The window is an AppWindow. That means that you can drop icons inside the window and it will be loaded. If you drop a disk/drawer the filerequester will be opened in that disk/drawer. -Added ToolTypes PRERUN y POSTRUN for running of commands right before the emulation is started, and before the emulation is stopped. -Before PRERUN the caches status is stored, and is restored before POSTRUN. -The emulator is no longer ß (BETA). That means that the interface is complete and the emulator is stable. The precision of emulation isn't included in the ß consideration, because if it where included the emulator could remain ß forever!! This is NOT a resignation to improve the emulation ;-) 39.16 (12-October-94) -Added ARexx functions: ClearAbort, ReadAbort and NoReload. -Added the 'Abort ARexx' gadget, to stop the ARexx scripts. Anyway, the script is the one that must read the gadget and decide the appropriate action. 39.17 (27-October-94) -Modified some instructions that uses de P/V flag. -Created an OCS/ECS version of the emulator. This version don't have FLASH attributes (instead they are inverted) and the colour emulation is slower than the AGA version. These are the only differences between the OCS/ECS version and the AGA version. (distributed as ZXAM Spectrum Emulator 1.5) 1.6 39.18 (14-November-94) -Now the emulator allocates correctly the audio channel 0. If the channel isn't available, a requester is showed and the emulation will not run. 39.19 (6-December-94) -Added the ZXAMDisassemble ARexx function, that disassembles Z80 code from the spectrum's memory. -Fixed a problem with keyboard and some games (like the DINAMIC ones). -Added a menu to enable/disable the audio-CIA sync. -Added the CIASYNC tooltype. -Added a menu to select the mode of the ROM's SAVE routine. Can be redirected to TAPE, DISK or DISK crunching the data with powerpacker.library. Pressing CANCEL a BREAK will be performed inside the emulator. -Added a menu to select the mode of the ROM's LOAD routine, that can be redirected to TAPE or DISK. -The CIA reading is better. -Now the emulator can use any CIA available. Before the emulator needed specifically the TIMER-B of CIA-B. -The CIA timer is allocated only during the emulation. -Fixed a problem of the FLASH with processors with data cache (030 and 040). -Added support for loading the Z80 snapshots. 39.20 (22-December-94) -Fixed a problem with Arexx scripts and paths with spaces. -Added the LOADMODE and SAVEMODE tooltypes. -Fixed a problem with the filename extension when doing 'save program'. -The games can be loaded by their 'default tool' o doing multi-selection. -Added to the Disassemble function the possibility of printing addresses/data in decimal or hexadecimal. -Added to Disassemble the printing of destination address of relative jumps. -Now the transfer is no more affected by the Save Mode menu, and always does the SAVE to tape. -Added support for loading NEW Z80 format (2.01). Older versions only can load the OLD Z80 format (1.45). -Modified the ZXAMParseLoaded() ARexx function to load and parse Z80 snapshots. -Removed the menu that enabled to enable/disable the audio sync with CIA. Removed the CIASYNC ToolType too. -Fixed a minor bug when saving in PC_PP format. -The emulator now allocates the 4 audio channels, for a forthcoming AY-3-8912 emulation. -The emulator is now crunched with Imploder 4.0. Before it was crunched with powerpacker, but the decrunching header caused some gurus in low memory conditions. (distributed as ZXAM Spectrum Emulator 1.6) 1.6b 39.21 (19-January-94) -Fixed a bug in the loading of Z80 snapshots. The emulator refused to load old (v1.45) Z80 snapshots if they where compressed. This bug was due to wrong information in the "Z80" v1.45 manual :-( -Added the possibility of loading (but not saving) snapshots in KGB format. -Modified some instructions. Now these instructions increments correctly the R register. -Some enhancements in the flags emulation. -Added an ARexx script for disassembling, BASIC listing searching of pokes, etc... It's a kind of monitor (Made by Leo Cocaña. Thanks Leo! :-) -Fixed two bugs in the embedded disassembler (in the 'ld hl,(nn)' and 'ld (nn),de' instructions). -Added the ARexx functions LoadMode(), SaveMode(), ActLoadMode() y ActSaveMode(). This way the new menu 'options' can be controlled from ARexx too. -Added the ARexx function About() -Modified the ARexx function ParseLoaded() for parse the KGB snapshots too. -Now 'Reload' works after a 'Save program'. -After 'Reset & Run' the 'Reload' shortcut is disabled (like the gadget). -Embedded a 1 second pause at the end of the ROM's SAVE routine. This is for programs that SAVE headers and blocks without pause between them (like the GENS assembler). -Added ARexx functions FindBlock() and DoChecksum(). -Added ARexx functions BreakPoint(), Trace(), DoInt() and BlockOfRegs(). With these functions you can execute Z80 code step-by-step, and put breakpoints. -Modified the ARexx function GetReg(). Now it has a second parameter (optional) that sets the format of the result (decimal or hexadecimal). -Now, when an ARexx script is running, the 'close window' events aren't queued anymore, and the menues are disabled. -Fixed a bug in the 'Reload' routine after doing SAVE in PC_PP format. (distributed as ZXAM Spectrum Emulator 1.6b) [0;1mFUTURE (near future?... or FAR future?)[0m When finished there will be two versions: - FAST version: with external tape loader (like the Spectrum Emulator 1.7). Some things, like BCD, R register, etc... aren't emulated. - FULL version: with REAL TIME LOADING (like the real Spectrum). It will load anything, even the protected programs. It will run over Amiga 4000, and maybe over Amiga 1200 with FAST 32 bits. The emulation will be almost complete. Anyway, in this version the patch will be optional. As soon as I can get some true FAST memory for my Amiga 1200 I will begin to work seriously in the Real Time Loading. Without FAST memory the Amiga 1200 can't run fast enough for real time loading. Anyway, I am developing a shared library that will make any tape-loading routine useless. This is the 'clairvoyance.library', that will foresee the contents of any tape without even having to connect the cassette-player to the computer. In the future there will be a floppy disk version, and maybe a network version. [0;1mACKNOWLEDGMENTS[0m I wish to thank to: - Fco Javier Cocaña Galán, Leonardo Cocaña Galán and Juan A. Estela Valín for their friendship and suggestions. - Commodore-Amiga Inc for create the very best computer in the world. - Motorola for their powerful and flexible microprocessors. - Nico François for create the reqtools.library and powerpacker.library. - Jan van den Baard for the incredibly useful GadToolsBox. - IBM and Atari for create so bad computers, making very easy my choosing for the Amiga. - Miguel Barnosi, Sysop of TANIT-BBS, for sending the emulator to several BBS of Spain and for acting as a "bridge" between me and FidoNET, and for initiating me to the world of comms. - Alberto Ordoñez Tellez, Raúl Ureña Sánchez, Arturo Rubio Pavón, Javier López Cosialls and Sergi Martinez Colldeforn for encourage me and for their suggestions. - Andrew Pointon (England) for sending to me some .Z80 snapshot (without it I couldn't manage to implement the Z80 format) and some .TAP files. - Flávio Massao Matsumoto (Brazil) for sending to me the "ZX Spectrum FAQ" of Internet. Without it I couln't manage to implement the KGB snapshot format. - Jordy Mejias for passing to me the KBG disk, that I deleted a long time ago. [0;1mCONTACTS[0m If you have any information about file formats, please, send it to me along with a disk with some programs saved in that format. If you find some bug (NAH!) report me the conditions in that it was found (processor, memory, etc..). If the problem is with a Spectrum program, send it to me. I would like if you can send me a letter about the speed of the emulator in your computer. I have tested the emulator in an Amiga 4000/030 with FAST memory (runs a bit faster that the real Spectrum) and in my Amiga 1200 without FAST (sob!). To report me the speed you can measure the time taken for some operation that I can reproduce in my 1200 and Spectrum +2A, like a RESET, a BASIC loop (please, send me the listing of the loop), or any other thing. I am very interested in the speed over an Amiga 1200 with FAST 32 bits and an Amiga 4000/040. Try to run the program _SpeedTest_.SP that is along with the emulator. For sending suggestions, bugs, information interchange, etc., contact me at the following address: Antonio J. Pomar Rosselló C/ Alférez Cerdá nº 13-bajos Palma de Mallorca 07014 Baleares (Spain) You can send me e-mail trough FidoNet: Toni Pomar (2:343/119.80). or AmigaNet: Toni Pomar (39:190/1.80). or InterNet: tpomar@penedes.mazanet.encomix.com Palma de Mallorca 14-January-1994 NOTE: my knowledge of English is VERY limited, and this text is a good sample of this fact. IF (you=spanish) OR (you KNOW spanish) THEN GOTO ZXAM_SpectrumAGA.DOCesp : REM The spanish DOC in much more detailed! ELSE READ ZXAM_SpectrumAGA.DOCeng : REM Sorry. I hope that you don't get headache! ENDIF NOTE2: if you know about a Dragon 32 emulator for the Amiga, please let me know. I know a friend of mine that wants that I program such an emulator. I think that some times there is a justification for murder...(AARGH!!). [0m[1 p